home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 June: Reference Library / Dev.CD Jun 99 RL Disk 1.toast / Technical Documentation / Macintosh Technotes and Q&As / technotes / tn / Apple_Guide_Variables / Source / AGValues.c < prev    next >
Encoding:
C/C++ Source or Header  |  1997-12-10  |  10.6 KB  |  350 lines  |  [TEXT/R*ch]
  1. /*
  2.   File:              AGValues.c
  3.   Contains:   Functions for installing and handling AG handlers
  4.                           Also Adds the additional apple event handlers
  5.   Written by:    Don Swatman
  6.   Copyright:    © 1996 by Apple Computer, Inc., all rights reserved.
  7. */
  8.  
  9. #include <AppleGuide.h>
  10. #include <AppleEvents.h>
  11.  
  12. #include "AGValues.h"
  13.  
  14. //===============================================================================
  15. //        AGValues
  16. //
  17. // This unit adds context check handlers and apple events to allow apple guides
  18. // to store values and then interogate them.
  19. // There are two calls into the unit. 
  20. //      OSErr InitAGStuff();  // This installs the handlers
  21. //      void RemoveAGStuff(); // This removes them
  22. //
  23. // Currently it only sets or clears 3 values. This can be easily expanded.
  24. //
  25. //-------------------------------------------------------------------------------
  26. //
  27. //        Apple Guide - Context Checks
  28. //
  29. // The helper app has a context check call back for 'vals' context check. More
  30. // details can be found below.
  31. //
  32. //-------------------------------------------------------------------------------
  33. //
  34. //        Apple Events
  35. //
  36. // The helper app understands the 'Vals' class. This is an unregistered class
  37. // which I've invented purely for demonstration puposes. The 'Cler' event id is
  38. // used to clear all the stored values. 'Clr1', 'Clr2' and 'Clr3' set the values
  39. // 1-3 respectively to 0, and 'Set1', 'Set2' and 'Set3' set the values to 1
  40. //
  41. //===============================================================================
  42.  
  43.  
  44. //==============================================
  45. // Constants
  46. //==============================================
  47.  
  48. // Maximum number of values that can be stored by app
  49. #define kMaxAGEntries 100  
  50.  
  51.  
  52. //==============================================
  53. //  Globals
  54. //==============================================
  55.  
  56. // Storage for coach mark and context check references
  57.  
  58. AGCoachRefNum   coachRefNum;
  59. AGContextRefNum contextRefNum;
  60.  
  61. // Storage for values
  62.  
  63. long gAGValues[kMaxAGEntries];
  64.  
  65. //==============================================
  66. // Prototypes
  67. //==============================================
  68.  
  69. pascal OSErr MyObjectCoachCallBack ( Rect *pRect, Ptr name, long refCon );
  70.  
  71. OSErr MySetContextResult( Boolean result,
  72.                                                     Ptr     *outMessage,
  73.                                                     Size    *outSize );
  74.  
  75. pascal OSErr MyContextCallBack( Ptr   pInputData,
  76.                                                                 Size  inputDataSize,
  77.                                                                 Ptr   *ppOutputData,
  78.                                                                 Size  *pOutputDataSize,
  79.                                                                 AGAppInfoHdl hAppInfo );
  80.  
  81. void    ClearAllAGValues();
  82.  
  83. pascal OSErr SetAGValues1    ( const AppleEvent *message, const AppleEvent *reply, long refcon);        
  84. pascal OSErr ClearAGValues1    ( const AppleEvent *message, const AppleEvent *reply, long refcon);            
  85. pascal OSErr SetAGValues2    ( const AppleEvent *message, const AppleEvent *reply, long refcon);        
  86. pascal OSErr ClearAGValues2    ( const AppleEvent *message, const AppleEvent *reply, long refcon);            
  87. pascal OSErr SetAGValues3    ( const AppleEvent *message, const AppleEvent *reply, long refcon);        
  88. pascal OSErr ClearAGValues3    ( const AppleEvent *message, const AppleEvent *reply, long refcon);            
  89.  
  90. pascal OSErr ClearAGValues    ( const AppleEvent *message, const AppleEvent *reply, long refcon);            
  91.  
  92.  
  93. //==============================================
  94. //  Initalize and remove Apple Guide call backs
  95. //==============================================
  96.  
  97. //----------------------------------------------
  98. //  InitAGStuff
  99. //
  100. // Clears all the values stored by the application
  101. // Install object coach handler
  102. // Install context check handler
  103. // Initialize the AppleEvent handlers table used
  104. //   for helping the guide file
  105. //----------------------------------------------
  106.  
  107. OSErr InitAGStuff()
  108. {
  109.     OSErr theErr = noErr;
  110.     short count;
  111.     
  112. // Clear all the values stored by the application
  113.     ClearAllAGValues();
  114.         
  115. // Install object coach handler
  116.     theErr = AGInstallCoachHandler( NewCoachReplyProc(MyObjectCoachCallBack), 0, &coachRefNum );
  117.     if (theErr)
  118.         DebugStr("\pGot an Err - AGInstallCoachHandler ");
  119.             
  120. // Install context check handler. MyContextCallBack will get called when a 
  121. // context check of 'Vals' is queried by the Guide
  122.  
  123.     theErr = AGInstallContextHandler( NewContextReplyProc(MyContextCallBack), 'Vals', 0, &contextRefNum );
  124.     if (theErr)
  125.         DebugStr("\pGot an Err - AGInstallContextHandler ");
  126.     
  127. // set up the dispatch table for the AppleEvents
  128.     theErr = AEInstallEventHandler( 'Vals', 'Cler', NewAEEventHandlerProc(ClearAGValues), 0, false) ;
  129.  
  130.     theErr = AEInstallEventHandler( 'Vals', 'Clr1', NewAEEventHandlerProc(ClearAGValues1), 0, false) ;
  131.     theErr = AEInstallEventHandler( 'Vals', 'Clr2', NewAEEventHandlerProc(ClearAGValues2), 0, false) ;
  132.     theErr = AEInstallEventHandler( 'Vals', 'Clr3', NewAEEventHandlerProc(ClearAGValues3), 0, false) ;
  133.  
  134.     theErr = AEInstallEventHandler( 'Vals', 'Set1', NewAEEventHandlerProc(SetAGValues1), 0, false) ;
  135.     theErr = AEInstallEventHandler( 'Vals', 'Set2', NewAEEventHandlerProc(SetAGValues2), 0, false) ;
  136.     theErr = AEInstallEventHandler( 'Vals', 'Set3', NewAEEventHandlerProc(SetAGValues3), 0, false) ;
  137.     
  138.     return theErr;
  139. }
  140.  
  141. //----------------------------------------------
  142. //  RemoveAGStuff
  143. //
  144. // Removes object coach handler
  145. // Removes context check handler
  146. //----------------------------------------------
  147.  
  148.  
  149. void RemoveAGStuff()
  150. {
  151.     OSErr theErr;
  152.     
  153.     theErr = AGRemoveContextHandler( &contextRefNum );
  154.     theErr = AGRemoveCoachHandler( &coachRefNum );
  155.  
  156. }
  157.  
  158. //==============================================
  159. //  MyObjectCoachCallBack
  160. //
  161. // This is called whenever a guide requests an object coach
  162. // from this application.
  163. //   "pRect"  pointer to a rectangle you should retun the coaches rect in
  164. //   "name"   contains a null terminated string passed from the Guide 
  165. //            file. This is the final parameter in Apple Guides 
  166. //            <Define Object Coach> command.
  167. //   "refCon" This is the reference constant passed in AGInstallCoachHandler.
  168. //            In this case 0.
  169. //
  170. // As this is only for demo purposes, this call back just returns a 
  171. // 100x100 square.
  172. //==============================================
  173.  
  174. pascal OSErr MyObjectCoachCallBack ( Rect *pRect, Ptr name, long refCon )
  175. {
  176.     OSErr theErr = noErr;
  177.     
  178.     SetRect ( pRect, 100,100, 200,200);
  179.     
  180.     return theErr;
  181. }
  182.  
  183. //==============================================
  184. //  MyContextCallBack
  185. //
  186. // This is called whenever a 'vals' context check is made. The
  187. // additional parameters in Apple Guides <Define Context Check>
  188. // are passed in "pInputData". In this case it contains 2 longs
  189. // which correspond to the PassedAGParamType structure.
  190. //   "command" is either 1 or 0. If it is zero then it tests if 
  191. //             the specified value is zero, if it is 1 then it 
  192. //             tests if the specified value is non-zero.
  193. //   "index"   is used to specify which of the "gAGValues" is to
  194. //             be tested
  195. //
  196. // Once a result, true or false, has been determined, MySetContextResult()
  197. // is used to put the result into ppOutputData and pOutputDataSize. This
  198. // is part of a far wider mechanism so a pointer to a boolean must be
  199. // created which contains 1 for true and 0 for false
  200. //
  201. //==============================================
  202.  
  203.  
  204. struct PassedAGParamType
  205. {
  206.     long command;
  207.     long index;
  208. };
  209.  
  210. typedef struct PassedAGParamType PassedAGParamType,
  211.     *PassedAGParamPtr, **PassedAGParamHdl;
  212.  
  213.  
  214. pascal OSErr MyContextCallBack( Ptr   pInputData,
  215.                                                                 Size  inputDataSize,
  216.                                                                 Ptr   *ppOutputData,
  217.                                                                 Size  *pOutputDataSize,
  218.                                                                 AGAppInfoHdl hAppInfo )
  219. {
  220.     OSErr   theErr = noErr;
  221.     Boolean checkResult = false;
  222.     long    count;
  223.  
  224. // Check the index is within range
  225.  
  226.     if (((PassedAGParamPtr)pInputData)->index >= kMaxAGEntries)
  227.         checkResult = false;
  228.     else
  229.  
  230. // Work out whether we need to return true or false
  231.  
  232.         if (((PassedAGParamPtr)pInputData)->command == 1)
  233.             checkResult = gAGValues[((PassedAGParamPtr)pInputData)->index - 1] != 0;
  234.         else
  235.             checkResult = gAGValues[((PassedAGParamPtr)pInputData)->index - 1] == 0;
  236.     
  237. // Set up the return values ppOutputData and pOutputDataSize
  238.  
  239.     theErr = MySetContextResult ( checkResult, ppOutputData, pOutputDataSize );
  240.     
  241.     return theErr;
  242. }
  243.  
  244. //==============================================
  245. //  MySetContextResult
  246. //
  247. // This is sets up the reply, ppOutputData and pOutputDataSize
  248. // used by custom context checks. It creates a pointer and moves
  249. // the value in result into it.
  250. //
  251. //==============================================
  252.  
  253. OSErr MySetContextResult( Boolean result,
  254.                                                     Ptr     *outMessage,
  255.                                                     Size    *outSize )
  256. {
  257.     Ptr   pOut;
  258.     Size  theSize = sizeof ( Boolean );
  259.     OSErr theErr = noErr;
  260.     
  261.     pOut = NewPtr (theSize);
  262.     if ( pOut )
  263.     {
  264.         BlockMove( (void *)&result, pOut, theSize );
  265.         *outSize = theSize;
  266.         *outMessage = pOut;
  267.     }
  268.     else
  269.         theErr = MemError();
  270.  
  271.     return theErr;    
  272. }
  273.  
  274. //==============================================
  275. //  ClearAllAGValues
  276. //
  277. // Sets all the guides stored values in gAGValues to 0.
  278. //==============================================
  279.  
  280. void ClearAllAGValues()            
  281. {
  282.     long    count;
  283.  
  284.     for (count=0;count < kMaxAGEntries;count++)
  285.         gAGValues[count] = 0;
  286. }
  287.  
  288.  
  289.  
  290. //===============================================================================
  291. //   Event Handlers
  292. //===============================================================================
  293.  
  294.  
  295. //-------------------------------------------------------------------------------
  296. //       Clear all AG stored values
  297. //
  298. // 
  299. //-------------------------------------------------------------------------------
  300. pascal OSErr ClearAGValues(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  301.  {
  302.     ClearAllAGValues();
  303.     return( noErr );
  304. }
  305. //-------------------------------------------------------------------------------
  306. //       Set AG stored values to 1
  307. //-------------------------------------------------------------------------------
  308.  
  309. pascal OSErr SetAGValues1(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  310. {
  311.     gAGValues[0] = 1;
  312.     return( noErr );
  313. }
  314.  
  315. pascal OSErr SetAGValues2(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  316. {
  317.     gAGValues[1] = 1;
  318.     return( noErr );
  319. }
  320.  
  321. pascal OSErr SetAGValues3(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  322. {
  323.     gAGValues[2] = 1;
  324.     return( noErr );
  325. }
  326.  
  327. //-------------------------------------------------------------------------------
  328. //       Clear AG stored values to 0
  329. //-------------------------------------------------------------------------------
  330.  
  331. pascal OSErr ClearAGValues1(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  332. {
  333.     gAGValues[0] = 0;
  334.     return( noErr );
  335. }
  336.  
  337. pascal OSErr ClearAGValues2(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  338. {
  339.     gAGValues[1] = 0;
  340.     return( noErr );
  341. }
  342.  
  343. pascal OSErr ClearAGValues3(const AppleEvent *message, const AppleEvent *reply, long refcon)            
  344. {
  345.     gAGValues[2] = 0;
  346.     return( noErr );
  347. }
  348.  
  349.  
  350.